MacHack 1993/MacHack 1993.toast/MacHack™ 1987-1992/MacHack™ '90/Other Stuff/Demos ƒ/TOPS SoftTalk Package/SoftTalk.h

C/C++ Source or Header | 1989-09-06 | 11.8 KB | 405 lines | [TEXT/KAHL]

/*
------------------------------------------------------------------------------
|    Sun Microsystems, TOPS Division
|    950 Marina Village Parkway
|    P.O. Box 4016
|    Alameda, CA 94501
|
|    Copyright (c) 1989 Sun Microsystems, Inc. All rights reserved.
|
|    Sun considers its source code as an unpublished, proprietary trade secret,
|    and it is available only under strict license provisions. This copyright
|    notice is placed here only to protect Sun in the event the source is deemed
|    a published work. Disassembly, decompilation, or other means of reducing the
|    object code to human readable form is prohibited by the license agreement
|    under which this code is provided to the user or company in possession of
|    this copy.
|
|    RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the Government
|    is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the
|    Rights in Technical Data and Computer Software clause at DFARS 52.227-7013
|    and in similar clauses in the FAR and NASA FAR supplement.
------------------------------------------------------------------------------
*/


/*
================================================================================
**
**    Project:    SoftTalk
**
**    File:        SoftTalk.h
**
**    Purpose
**        This file presents the interface to the SoftTalk module
**
**    Usage:
**        include this file into any module that will use SoftTalk.
**
**    ----------------------------------------------------------------------------
**
**    Version        Date        Author        Description
**    -------        ----        ------        -----------
**    1.0.2        30-Aug-89     MAC            Second draft.
**    1.0.1        17-Aug-89     MAC            First draft.
**
================================================================================
*/


#ifndef    __SoftTalk__
#define __SoftTalk__


/*
**    ----------------------------------------------------------------------------
**        INCLUDES
**    ----------------------------------------------------------------------------
*/
#include "StdHdr.h"


/*
**    ----------------------------------------------------------------------------
**        CONST
**    ----------------------------------------------------------------------------
*/
#define    kDefaultRequests    (0)
    /* use for STOpenServer, STOpenSession if you want the default number of buffers */

#define    kStillLooking    (-1)
    /* returned by STList if it started an async lookup */

    /* predefined service routine ranks */
#define    kInterruptRank    (0)
#define    kSystemTaskRank    (1)

    /* codes for the mandatory service routines that must be registered by every server */
#define    kAcceptSessionCode    (0x0004)
#define    kFreeSessionCode    (0x0006)

    /* errors */
#define kEInitFailed (-1)
#define kESuccess (0)
#define    kCloseConnectionMsg    (0)



/*
**    ----------------------------------------------------------------------------
**        TYPE
**    ----------------------------------------------------------------------------
*/
typedef INT32 STResult;
    /* the return value from a SoftTalk function */

typedef void* STServer;
    /* the "magic cookie" for a SoftTalk server */

typedef void* STSession;
    /* the "magic cookie" for a SoftTalk session */

typedef INT32 STArg;
    /* the universal type for all SoftTalk function arguments */

typedef    INT32    (*Func32Ptr)();
    /* ptr to a function that returns an INT32 */

typedef    void    (*FuncVoidPtr)();
    /* ptr to a function that returns void */


typedef    UINT32    AddrBlock;
    /*
    **    This is a flaw in the SoftTalk armour against AppleTalk.
    **    In order to find the owner of a duplicate name, we have
    **    to know the structure of an AppleTalk network address,
    **    and some of the private part of the list item structure.
    */

typedef    struct STServerSpec {
    struct STServerSpec*    link;
    BYTE*                name;
    INT16                len;
    BYTE*                stat;
    AddrBlock*            net;
} STServerSpec, *STServerSpecPtr;
    /* List elements returned by the STList command */




/*
**    ============================================================================
**        PROTOTYPES
**    ============================================================================
*/


/*
**    ============================================================================
**        Common Entry Points
**    ============================================================================
*/

STResult STInitialize(void);
    /*
    |    Purpose:    initialize the SoftTalk library
    |
    |    Usage: Call from a client module to intialize the SoftTalk library.
    */


STResult STGetVersion(void);
    /*
    |    Purpose: Obtain the version number of SoftTalk.
    */

void STGetSizes(UINT32* pCommandMax, UINT32* pWriteMax, UINT32* pReadMax, UINT32* pStatusMax);
    /*
    |    Purpose: Determine implementation dependent maximums:
    |
    |    Usage:
    */



/*
**    ============================================================================
**        Server Entry Points
**    ============================================================================
*/

STResult STOpenServer(STServer* pServerID, UINT32 nRequests);
    /*
    |    Purpose:
    |        Open a SoftTalk server, specifying the desired number of concurrent
    |        requests .  Allocate and return a server-id (STServer) and return the actual
    |        number of concurrent client requests that can be serviced.
    |
    |    Usage:
    |        Called externally after STInitialize(). Pass in a pointer to the STServer
    |        ident, as well as the number of concurrent requests desired.
    */



STResult STCloseServer(STServer serverID);
    /*
    |    Purpose: Close a SoftTalk server.
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer().  Returns kESuccess, or a
    |        negative error code.
    */



STResult STAlias(STServer serverID, BYTE* name);
    /*
    |    Purpose:    give the server a name
    |        Give the server specified by "serverID" a human-readable name.  This name is
    |        typically of the form "name:type@zone" (standard AppleTalk).
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer().  Returns kESuccess, or a
    |        negative error code.
    */



STResult STUnalias(STServer serverID, BYTE* name);
    /*
    |    Purpose:    remove an alias for the server
    |        Remove a previous alias for the server.
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer().  Returns kESuccess, or a
    |        negative error code.
    */



STResult STSetStatus(STServer serverID, BYTE* block, UINT32 blockSize);
    /*
    |    Purpose:    set the server's status bytes
    |        Set the "status" block that is associated with the server.  This block
    |        is not interpreted by SoftTalk and can be used to help a client get info
    |        about the server in a client specific way (i.e. icon info, etc.).
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer(), a pointer to the block
    |        and the length of the block of data.  The maximum size block that SoftTalk can
    |        handle is implementation dependant and can be determined by calling GetSizes()
    |        (see below).  Returns kESuccess, or a negative error code.
    */



STResult STRegister(STServer serverID, UINT32 code, Func32Ptr F, UINT32 rank, BYTE* format);
    /*
    |    Purpose:    register a service routine
    |        Register a service routine for the server specified by "serverID".
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer(), the two letter code that
    |        designates the routine (as in 'F1'), the ptr to the service routine, the
    |        rank of the routine, and a string that describes the format of the arguments.
    |        The rank is used for scheduling purposes (exactly how???).  The service routine
    |        may be called at interrupt times so special steps need to be taken if it accesses
    |        globals.  Also, currently the service routine is called with arguments in
    |        registers d0-d7, so assembly glue is needed to convert this into a C function call.
    |        Returns kESuccess, or a negative error code.
    */



STResult STReply(BYTE* buffer, UINT32 count, INT32 result);
    /*
    |    Purpose:    return data to client
    |        Return data into a client's buffer within a service routine.
    |
    |    Usage:
    |        If one of the arguments to a service routine is a ptr/len pair this call
    |        is used to return the data into the client's buffer.
    |        Return values???
    */



STResult STHear(STServer serverID, UINT32 rank);
    /*
    |    Purpose:    accept a service request
    |        Tell SoftTalk that you are willing to accept a service request.  How does
    |        SoftTalk's scheduling mechanism work???
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer(), and the rank of the routine
    |        you are willing to service.  If a routine was serviced, then STHear returns
    |        non-zero; if a routine was _not_ serviced then STHear() returns zero.
    */



STResult STSignal(STServer serverID, STSession sessionID, INT32 message);
    /*
    |    Purpose:
    |        Allow the server to communicate a message to the client.  Can be used for
    |        exceptions, panic, shutdown, etc.
    |
    |    Usage:
    |        Call with a server-id returned by STOpenServer(), the session-ID for
    |        a particular client (obtained from the client) and a message.  If teh message
    |        is equal to kCloseConnectionMsg, the connection is terminated.  Otherwise,
    |        the message is passed on to the client.
    |        Returns kESuccess, or a negative error code.
    */





/*
**    ============================================================================
**        Client Entry Points
**    ============================================================================
*/

STResult STList(STServerSpecPtr* listElts, BYTE* spec);
    /*
    |    Purpose:
    |        Locate all servers that match a name specification.
    |
    |    Usage:
    |        Pass in an NBP search specification (i.e. "=:AFPServer:*"), and the address
    |        of the head of the linked-lists of the found servers.  STList() returns
    |        the number of servers found, or a negative error code.  If STList() returns the
    |        the special value kStillLooking, and async lookup has been triggered, and subsequent
    |        calls to STList() with the same search-spec will return the number of servers
    |        found since the last call.
    */



STResult STUnlist(BYTE* spec);
    /*
    |    Purpose:
    |        Deallocate the list of ServerSpecs that matches the given NBP search-spec.
    |
    |    Usage:
    |        Call with the same NBP spec used for the STList() call.
    |        Returns kESuccess, or a negative error code.
    */



STResult STOpenSession(STSession* pSessionID, BYTE* spec, Func32Ptr Notify, UINT32 nRequests);
    /*
    |    Purpose:
    |        Open a session with the server specified in the NBP spec.
    |
    |    Usage:
    |        Call with the NBP spec for the desired server, a ptr to a special
    |        interrupt-level service routine Notify(), the number of buffers needed for
    |        multiple async requests.  The routine will allocate a sessionID.
    |        Returns the actual number of buffers allocated, or a negative error code.
    */



STResult STCloseSession(STSession sessionID);
    /*
    |    Purpose:
    |        Close the session identified by sessionID.
    |
    |    Usage:
    |        Call with a ssession-id returned by STOpenSession().
    |        Returns kESuccess, or a negative error code.
    */



STResult STAsk(STSession sessionID, INT32* pResult, UINT32 code, BYTE* format,...);
    /*
    |    Purpose:
    |        Execute the specified service routine on the server with the given arguments.
    |
    |    Usage:
    |        Call with a session-id returned by STOpenSession(), a ptr to the return value,
    |        the code for the routine to be invoked (i.e. 'F1'), the format string describing
    |        the arguments, and then the arguments themselves.
    |        Returns kESuccess, or a negative error code.
    */



STResult STAsync(STSession sessionID, FuncVoidPtr Done, UINT32 arg, UINT32 code, BYTE* format, ...);
    /*
    |    Purpose:
    |        Trigger the execution of the specified service routine on the server
    |        with the given arguments.
    |
    |    Usage:
    |        Call with a session-id returned by STOpenSession(), a ptr to a interrupt-level
    |        completion routine Done(INT32 error, INT32 result, INT32 arg),
    |        the code for the routine to be invoked (i.e. 'F1'), the format string describing
    |        the arguments, and then the arguments themselves.  The value arg is not interpreted
    |        by SoftTalk; it is for the convenience of the client and will be passed into
    |        the completion routine.  This could be used, for example, to pass the address
    |        of a variable to the completion routine.
    |        Returns kESuccess, or a negative error code.
    */



void STPoll(void);
    /*
    |    Purpose: This does nothing on the Macintosh.
    */





#endif